/**
 * 组件物料协议
 * 
 * 该协议定义了组件在物料面板中的注册和使用规范。
 * 每个组件需要实现该协议才能被系统识别和使用。
 */

import type { 
  ComponentType, 
  ComponentCategory, 
  PropDefinition
} from '@/types';

/**
 * 组件物料元数据
 * 定义组件在物料面板中的展示信息
 */
export interface ComponentMeta {
  type: ComponentType;       // 组件类型标识
  category: ComponentCategory; // 组件分类
  title: string;             // 组件名称
  description?: string;      // 组件描述
  icon?: string;             // 组件图标
  thumbnail?: string;        // 组件缩略图
  tags?: string[];           // 组件标签，用于搜索
}

/**
 * 组件默认配置
 * 定义组件的默认属性和布局
 */
export interface ComponentDefaults {
  props: Record<string, unknown>;   // 默认属性值
  layout: {                        // 默认布局配置
    w: number;                     // 默认宽度(网格单位)
    h: number;                     // 默认高度(网格单位)
    minW?: number;                 // 最小宽度
    minH?: number;                 // 最小高度
    maxW?: number;                 // 最大宽度
    maxH?: number;                 // 最大高度
  };
}

/**
 * 组件能力配置
 * 定义组件的特殊功能和限制
 */
export interface ComponentCapabilities {
  isContainer?: boolean;           // 是否为容器组件
  allowChildren?: boolean;         // 是否允许包含子组件
  childrenTypes?: ComponentType[]; // 允许的子组件类型
  maxChildren?: number;            // 最大子组件数量
  isCRUD?: boolean;                // 是否为CRUD组件
  requiredModel?: string;          // 必需的数据模型名称
  hasCustomEditor?: boolean;       // 是否有自定义编辑器
}

/**
 * 组件注册协议
 * 完整定义一个组件的所有注册信息
 */
export interface ComponentRegistration {
  meta: ComponentMeta;              // 组件元数据
  propDefinitions: PropDefinition[];  // 属性定义列表
  defaults: ComponentDefaults;      // 默认配置
  capabilities: ComponentCapabilities; // 组件能力
  component: React.ComponentType<Record<string, unknown>>; // 实际组件引用
}

/**
 * 组件注册表
 * 用于全局管理已注册的组件
 */
export interface ComponentRegistry {
  components: Record<string, ComponentRegistration>;
  registerComponent: (component: ComponentRegistration) => void;
  getComponent: (type: ComponentType) => ComponentRegistration | undefined;
  getComponentsByCategory: (category: ComponentCategory) => ComponentRegistration[];
  getAllComponents: () => ComponentRegistration[];
}

/**
 * 组件渲染属性
 * 在画布中渲染组件时使用的属性
 */
export interface ComponentRenderProps {
  id: string;
  type: ComponentType;
  props: Record<string, unknown>;
  children?: React.ReactNode;
  style?: React.CSSProperties;
  className?: string;
  onClick?: (e: React.MouseEvent) => void;
  onDoubleClick?: (e: React.MouseEvent) => void;
} 